Lua tutorial
Lua (or RCLua, when used in RigidChips), is a way to make your models do things on their own, react to there surroundings and themselves, and display information. It takes the form of a simple code, easy enough to learn. As with any code, programming or scripting language, it is useful to set it out neatly. A common way is to indent every level of code with Tab. If you are using RCD, then you can just start typing the Lua directly into the Lua section. Otherwise, Surround the Lua in Lua{ and } Functions The first thing you need to know about in RCLua are functions. In every model using Lua you need to have either function main() or the three On*() functions. In function main(), every line of code is executed once per frame. It is a more basic way to use RCLua. The On*() functions consist of three different functions, but you need to use all of them for the script to run correctly. The functions are: function OnInit() function OnReset() function OnFrame() OnInit function OnInit() is executed on the first frame after you load the model from file (via Open or Ctrl+O or Ctrl+U). This function is typically used to set variables. OnReset function OnReset() is executed on the first frame after you reset (via U or R) the model. Usually, this is the same as function OnInit(). OnFrame function OnFrame() is like function main() in that it is executed every frame. The OnFrame() has higher priority than main(), meaning that if there are both OnFrame() and main() in the same file, main() would not be called. Extra functions To add extra functions, you must type: function NameOfTheFunction() Then, to execute this function, you must write function() in another executed function. e.g. Lua{ function example() end function main() example() end } Absolute Statements The simplest thing you can do in Lua is create an absolute statement, or something that happens no matter what, as long as the function it is in is executed. This is done by saying Variable = value {operator} value e.g. ELEVATOR = ROLL + PITCH The operators are = + addition - subtraction * multiplication / division ^ to the power of As with most things, surrounding something in brackets tells the Lua to perform that operation first. e.g. ELEVATOR = (ROLL + PITCH) * 2 is equivalent to ELEVATOR = ROLL * 2 + PITCH * 2 'If' statements The next thing you can do is create a statement that only happens if something is happening, or while something is happening. The basic if statement is : if statement then to execute end e.g. if MODE 1 then ELEVATOR = ROLL + PITCH end The logic comparers are = is equal to =~ is not equal to < is smaller than > is greater than <= is smaller than or equal to >= is greater than or equal to NOTE: " " Checks equality, "=" forces it. In other words, " " is used in logic statements, and "=" is used to alter variables. This is very important, as it may affect the operation of your vehicle. You can also combine logic statements, using {and} or {or} e.g. if MODE 1 and GEAR > 0 then ________ end In this case, if MODE is one, and the gear value is larger than zero, it will execute the command. if MODE 1 or GEAR > 0 then ________ end In this one, if MODE is one, OR the gear value is larger than zero, OR both, it will execute the command. After the True statements, you can add in else, or elseif. Like this (for else): if statement then to execute if logic is true else to execute if logic is NOT true end Or like this (for elseif): if statement1 then to execute if logic1 is true elseif statement2 then to execute if logic2 is true end Or like this (combined): if statement1 then to execute if logic is true elseif statement2 then to execute if logic2 is true else to execute if ALL logic is NOT true end NOTE: You can use "elseif" as many times as you want, but "else" can only be used once. e.g. if MODE 1 then ELEVATOR = ROLL + PITCH else RUDDER = YAW + ROLL end Here, if the MODE = is one, then the ELEVATOR is the roll plus the pitch, but if that is NOT true, the RUDDER = YAW + ROLL. if MODE 1 then ELEVATOR = ROLL + PITCH elseif GEAR > 0 then RUDDER = YAW + ROLL end Here, if the MODE = is one, then the ELEVATOR is the roll plus the pitch, but if that is NOT true, AND the GEAR is greater than zero, the RUDDER = YAW + ROLL. NOTE: if statements can be stacked multiple times. Functions can also be executed in if statements. 'While' Loops A while loop is another type of loop, controlled by a single logic comparison. The syntax is: while comparison do here end It is a pretty simple function to understand, seeing as it is so easy to read! An example would be: Lua{ local count = 0; local hiddenValue = 34; local found = 0; function count(max) while(count < max) do if(count hiddenValue) then found = count; end count = count + 1; end if(count >= max) then count = 0; end end function main() count(100); out(0, "The hidden value found is "..found.."!"); end } Note: Strings cannot be joined with a + sign in Lua. Instead, use a double period/full stop: .. Don't be intimidated by this code, it's not as complicated as it looks! First off, we start by creating a local variable. A variable is a number that you can change within the code to whatever you want. They can also be character strings (Such as "Hello World!") or Boolean values (Either true or false). I made a variable called count, which is created with a value of 0. Notice how I made it outside of the main function, because the main function is called every frame, therefore the value would be set to 0 every frame if it was in the main function! Then is my function called count(). It takes a single argument, in this case a number called "max". When a function takes an argument, you pass it that argument by calling the function like this: foo(bar); Where foo() is the function, and "bar" is the argument. Inside that function, I have my while loop. Inside that while loop, I have the code to be executed if "count" is less than "max". What that code is doing is checking whether the count value is equal to this "hiddenValue". If it is, we set "found" to the value of "count", therefore the value of "hiddenValue"! Follow me? =P If not, we increment "count" by one so the loop can go back around and check again. Also in that function is a check to make sure count doesn't go above the max value we specified, in this case 100. If it does, it gets set back to 0. Only thing to do after that is call the function inside main(). I do this by writing "count(100);". This calls count() and sets "max" to 100. Then I output the hidden value using out(). The syntax is: out(lineNumber, "text"); Simple, eh? 'For' loops A very important ability in Lua is to call the same function multiple times per frame. This is especially useful in things like chainguns, radar and some other models. The basic format for a for loop is this: for declaration do here end The declaration usual looks like this: variable = min,max,increment The variable is a new local variable, that is created by the for loop and changes during each frame. It is only usable inside the loop. for i = 1,5 do out(i,i+2) end returns: line1: 3 line2: 4 line3: 5 line4: 6 line5: 7 The for loop will perform the code inside it multiple times per frame, (max-min)/increment times. The variable, in this case "i", changes each time the code is performed. Basically, it is this: 1) The variable starts as min. 2) code is performed. 3) increment is added to the variable (default is 1 if left blank) 4) Repeats steps 2-3 until the ariable is over max. for j = 1,5,2 do out(i,i+2) end returns: line1: 3 line2: line3: 5 line4: line5: 7 AS another example, we will try to script a 3D line contrail/cord. timer = 0 x,y,z = {},{},{} function cord() xtimer = _X(0) ytimer = _Y(0) ztimer = _Z(0) _SETCOLOR(16711680) for tdisp = 1,timer do _MOVE3D(xtdisp,ytdisp,ztdisp) _LINE3D(xtdisp-1,ytdisp-1,ztdisp-1) end timer = timer + 1 end Im guessing some of this looks like nonsense to you. First off, tables. To create a table, you create a variable and instead of assigning a number, boolean or string to it, you assign a table value, or "{}". Then, to call or assign a specific value, you use the "[]" brackets. You contain the assigner in the curly brackets, this can be either a number or "string" value. Example: table"any_value" = 6 table7465 = true table"another_string" = table7465 The next thing you may/may not know is 3D lines. They are pixel wide lines that are drawn in the RC world, often used as "targetting lasers". _SETCOLOR(col) _MOVE3D(x,y,z) _LINE3D(x,y,z) _SETCOLOR() Takes the decimal version of a #****** 6 digit hex color code, and sets the color for all lines after it is called. _MOVE3D() Sets the start position for the line. _LINE3D() Sets the end position for the line and draws it. It also sets the start possition for the next 3D line. (can be overwritten with _MOVE3D) function cord() works by setting up a table for the X,Y, and Z co-ordinates every frame. Then, the function stores the co-ordinates every frame in these tables. Then, it sets the color for the line to red. Finally, it uses a for loop to set the line starting position at the very first position, the draing to the next. This repeats until the end of the line is reached. Another function that works well with for loops is _G[]. _G[] is for calling a variable (or chipname). It takes "strings" and/or numerical values as its input. Example: for i = 1,4 do local gunangle = {} gunanglei = _G"GANG"..i end Where GANG1, GANG2, GANG3, GANG4 are variables defined in the VAL section of RCD. Seperate inputs are seperated with ".." End This is most of what you need to start scripting using Lua in RC! Have fun!